Setup Docker inside Proxmox

Alpine Linux Docker VM on Proxmox

A lightweight Docker host that just works.

Alpine is tiny, fast, maintained, and honestly a better long-term choice.

      
        bash
        
      

       .hddddddddddddddddddddddh.           root@docker01
      :dddddddddddddddddddddddddd:          -------------
     /dddddddddddddddddddddddddddd/         OS: Alpine Linux v3.24 x86_64
    +dddddddddddddddddddddddddddddd+        Host: KVM/QEMU Standard PC
  `sdddddddddddddddddddddddddddddddds`      Kernel: Linux 6.18.38-0-lts
 `ydddddddddddd++hdddddddddddddddddddy`     Uptime: 7 mins
.hddddddddddd+`  `+ddddh:-sdddddddddddh.    Packages: 131 (apk)
hdddddddddd+`      `+y:    .sddddddddddh    Shell: sh
ddddddddh+`   `//`   `.`     -sddddddddd    Display (Virtual-1): 1024x768, 60 Hz
ddddddh+`   `/hddh/`   `:s-    -sddddddd    Terminal: /dev/pts/0
ddddh+`   `/+/dddddh/`   `+s-    -sddddd    CPU: QEMU Virtual version 2.5+ (2) @ 3.59 GHz
ddd+`   `/o` :dddddddh/`   `oy-    .yddd    GPU: Red Hat, Inc. QXL paravirtual graphic card
hdddyo+ohddyosdddddddddho+oydddy++ohdddh    Memory: 481.02 MiB / 5.79 GiB (8%)
.hddddddddddddddddddddddddddddddddddddh.    Swap: 0 B / 4.00 GiB (0%)
 `yddddddddddddddddddddddddddddddddddy`     Disk (/): 1.23 GiB / 132.52 GiB (1%) - ext4
  `sdddddddddddddddddddddddddddddddds`      Local IP (eth0): 192.168.0.226/24
    +dddddddddddddddddddddddddddddd+        Locale: C.UTF-8
     /dddddddddddddddddddddddddddd/         
      :dddddddddddddddddddddddddd:                                  
       .hddddddddddddddddddddddh.

Why Alpine?

Alpine	Ubuntu
200MB install	Several GB
Fast boot	Slower
Very low RAM usage	Higher RAM usage
Minimal attack surface	Lots of unnecessary packages
Perfect for Docker	General-purpose OS

Requirements

Before starting:

Proxmox VE installed
Alpine Linux ISO downloaded
Internet access
VirtIO drivers (default in Proxmox)
IQ higher than 78

VM Configuration

Setting	Value
Machine	`q35`
BIOS	`SeaBIOS`
CPU Type	`host`
CPU	2-4 Cores
RAM	2-4 GB
Disk	32GB minimum (50GB recommended)
Disk Bus	VirtIO SCSI
Network	VirtIO
Bridge	vmbr0

Enable:

SSD Emulation
Discard
QEMU Guest Agent

Installation

Boot the Alpine ISO.

No password.

Run

      
        bash
        
      
setup-alpine

Question	Answer
Keyboard	us
Hostname	docker01
Network	eth0
IP	dhcp
Root Password	Strong Password
Timezone	Your Timezone
Mirror	Fastest
SSH	openssh
Disk	sda
Install	sys

Update Everything

      
        bash
        
      
apk update
apk upgrade

Install Packages

      
        bash
        
      
apk add \
docker \
docker-cli-compose \
qemu-guest-agent \
openssh \
bash \
curl \
wget \
git \
nano \
vim \
htop \
iftop \
bind-tools \
iproute2 \
ca-certificates

Enable Services

Docker:

      
        bash
        
      
rc-update add docker boot
service docker start

SSH:

      
        bash
        
      
rc-update add sshd
service sshd start

Guest Agent:

      
        bash
        
      
rc-update add qemu-guest-agent
service qemu-guest-agent start

Verify

      
        bash
        
      
docker version
docker compose version

service docker status
service sshd status
service qemu-guest-agent status

Test Docker

      
        bash
        
      
docker run hello-world

If this works, you're done with the OS.

Everything else is just containers.

Directory Structure

We will keep everything inside /opt/docker

      
        
        
      
/opt/docker
│
├── compose/
│   ├── portainer/
│   ├── nginx-proxy-manager/
│   ├── forgejo/
│   ├── ghost/
│   ├── navidrome/
│   └── ...
│
├── data/
│
├── backups/
│
└── scripts/

Create it:

      
        bash
        
      
mkdir -p /opt/docker/{compose,data,backups,scripts}

Portainer

      
        
        
      
/opt/docker/compose/portainer

docker-compose.yml:

      
        yaml
        
      
services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped

    ports:
      - "9000:9000"

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

Start:

      
        bash
        
      
docker compose up -d

Open this in browser:

      
        
        
      
http://ALPINE_SERVER_IP:9000

Useful Commands

Network

Get IP Address:

      
        bash
        
      
ip addr

Get Gateway:

      
        bash
        
      
ip route

DNS Test:

      
        bash
        
      
ping google.com

Check Internet:

      
        bash
        
      
ping 1.1.1.1

Test HTTPS Request:

      
        bash
        
      
curl https://google.com

System

Memory:

      
        bash
        
      
free -h

Disk:

Processes:

Services:

      
        bash
        
      
rc-status

Boot Services:

      
        bash
        
      
rc-update show

Docker

Containers:

      
        bash
        
      
docker ps
docker ps -a

Images:

      
        bash
        
      
docker images

Volumes:

      
        bash
        
      
docker volume ls

Networks:

      
        bash
        
      
docker network ls

Logs:

      
        bash
        
      
docker logs CONTAINER

Shell:

      
        bash
        
      
docker exec -it CONTAINER sh

Restart:

      
        bash
        
      
docker restart CONTAINER

Compose

Start:

      
        bash
        
      
docker compose up -d

Stop:

      
        bash
        
      
docker compose down

Restart:

      
        bash
        
      
docker compose restart

Logs:

      
        bash
        
      
docker compose logs -f

Update:

      
        bash
        
      
docker compose pull
docker compose up -d

DNS

Temporary:

      
        bash
        
      
nano /etc/resolv.conf

Example:

      
        
        
      
nameserver 1.1.1.1
nameserver 8.8.8.8

For Iran:

      
        
        
      
nameserver 178.22.122.100
nameserver 185.51.200.2

Troubleshooting

APK won't install packages

      
        bash
        
      
cat /etc/alpine-release
cat /etc/apk/repositories

apk update

Docker won't start

      
        bash
        
      
service docker status

      
        bash
        
      
service docker restart

Docker Hub timeout

Check:

      
        bash
        
      
ping 1.1.1.1
ping google.com

curl https://auth.docker.io

docker run hello-world

Most of the time it isn't Docker.

It's either:

DNS
Packet loss
ISP filtering
Bad routing

Final Layout

flowchart TD

    P[Proxmox]

    P --> VM

    subgraph VM["Alpine Docker VM"]

        Docker
        SSH
        QGA["QEMU Guest Agent"]

        Docker --> Compose

        Compose --> Portainer
        Compose --> NPM["Nginx Proxy Manager"]
        Compose --> Forgejo
        Compose --> Ghost
        Compose --> Navidrome
        Compose --> More["More Services..."]

    end

Filesystem

graph TD

root["/"]

root --> opt

opt --> docker

docker --> compose
docker --> data
docker --> backups
docker --> scripts

compose --> portainer
compose --> forgejo
compose --> ghost
compose --> navidrome
compose --> nginx
compose --> more